<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>执行匹配正则表达式</title>
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-base.css" />
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-medium.css" />

 </head>
 <body class="docs"><div class="navbar navbar-fixed-top">
  <div class="navbar-inner clearfix">
    <ul class="nav" style="width: 100%">
      <li style="float: left;"><a href="function.preg-match-all.html">« preg_match_all</a></li>
      <li style="float: right;"><a href="function.preg-quote.html">preg_quote »</a></li>
    </ul>
  </div>
</div>
<div id="breadcrumbs" class="clearfix">
  <ul class="breadcrumbs-container">
    <li><a href="index.html">PHP Manual</a></li>
    <li><a href="ref.pcre.html">PCRE 函数</a></li>
    <li>执行匹配正则表达式</li>
  </ul>
</div>
<div id="layout">
  <div id="layout-content"><div id="function.preg-match" class="refentry">
 <div class="refnamediv">
  <h1 class="refname">preg_match</h1>
  <p class="verinfo">(PHP 4, PHP 5, PHP 7, PHP 8)</p><p class="refpurpose"><span class="refname">preg_match</span> &mdash; <span class="dc-title">执行匹配正则表达式</span></p>

 </div>

 <div class="refsect1 description" id="refsect1-function.preg-match-description">
  <h3 class="title">说明</h3>
  <div class="methodsynopsis dc-description">
   <span class="methodname"><strong>preg_match</strong></span>(<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">string</span> <code class="parameter">$pattern</code></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">string</span> <code class="parameter">$subject</code></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$matches</code><span class="initializer"> = <strong><code>null</code></strong></span></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">int</span> <code class="parameter">$flags</code><span class="initializer"> = 0</span></span>,<br>&nbsp;&nbsp;&nbsp;&nbsp;<span class="methodparam"><span class="type">int</span> <code class="parameter">$offset</code><span class="initializer"> = 0</span></span><br>): <span class="type"><span class="type">int</span>|<span class="type"><span class="type false">false</span></span></span></div>

  <p class="para rdfs-comment">
  搜索<code class="parameter">subject</code>与<code class="parameter">pattern</code>给定的正则表达式的一个匹配.
  </p>
 </div>


 <div class="refsect1 parameters" id="refsect1-function.preg-match-parameters">
  <h3 class="title">参数</h3>
  <p class="para">
   <dl>
    
     <dt>
<code class="parameter">pattern</code></dt>

     <dd>

      <p class="para">
       要搜索的模式，字符串类型。
      </p>
     </dd>

    
    
     <dt>
<code class="parameter">subject</code></dt>

     <dd>

      <p class="para">
       输入字符串。
      </p>
     </dd>

    
    
     <dt>
<code class="parameter">matches</code></dt>

     <dd>

      <p class="para">
      如果提供了参数<code class="parameter">matches</code>，它将被填充为搜索结果。
      <var class="varname">$matches[0]</var>将包含完整模式匹配到的文本， <var class="varname">$matches[1]</var>
      将包含第一个捕获子组匹配到的文本，以此类推。
      </p>
     </dd>

    
    
     <dt>
<code class="parameter">flags</code></dt>

     <dd>

      <p class="para">
       <code class="parameter">flags</code> 可以被设置为以下标记值的组合：
       <dl>
        
         <dt>
<strong><code>PREG_OFFSET_CAPTURE</code></strong></dt>

         <dd>

          <p class="para">
          如果传递了这个标记，对于每一个出现的匹配返回时会附加字符串偏移量(相对于目标字符串的字节数)。
          注意：这会改变填充到<code class="parameter">matches</code>参数的数组，使其每个元素成为一个由
          第<code class="literal">0</code>个元素是匹配到的字符串，第<code class="literal">1</code>个元素是该匹配字符串
          在目标字符串<code class="parameter">subject</code>中的偏移量。
           <div class="informalexample">
            <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">'/(foo)(bar)(baz)/'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'foobarbaz'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PREG_OFFSET_CAPTURE</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
            </div>

            <p class="para">以上例程会输出：</p>
            <div class="example-contents screen">
<div class="cdata"><pre>
Array
(
    [0] =&gt; Array
        (
            [0] =&gt; foobarbaz
            [1] =&gt; 0
        )

    [1] =&gt; Array
        (
            [0] =&gt; foo
            [1] =&gt; 0
        )

    [2] =&gt; Array
        (
            [0] =&gt; bar
            [1] =&gt; 3
        )

    [3] =&gt; Array
        (
            [0] =&gt; baz
            [1] =&gt; 6
        )

)
</pre></div>
            </div>
           </div>
          </p>
         </dd>

        
        
         <dt>
<strong><code>PREG_UNMATCHED_AS_NULL</code></strong></dt>

         <dd>

          <p class="para">
           使用该标记，未匹配的子组会报告为 <strong><code>null</code></strong>；未使用时，报告为空的 <span class="type">string</span>。
           <div class="informalexample">
            <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">'/(a)(b)*(c)/'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'ac'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">'/(a)(b)*(c)/'</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'ac'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PREG_UNMATCHED_AS_NULL</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
            </div>

            <p class="para">以上例程会输出：</p>
            <div class="example-contents screen">
<div class="cdata"><pre>
array(4) {
  [0]=&gt;
  string(2) &quot;ac&quot;
  [1]=&gt;
  string(1) &quot;a&quot;
  [2]=&gt;
  string(0) &quot;&quot;
  [3]=&gt;
  string(1) &quot;c&quot;
}
array(4) {
  [0]=&gt;
  string(2) &quot;ac&quot;
  [1]=&gt;
  string(1) &quot;a&quot;
  [2]=&gt;
  NULL
  [3]=&gt;
  string(1) &quot;c&quot;
}
</pre></div>
            </div>
           </div>
          </p>
         </dd>

        
       </dl>

      </p>
     </dd>

    
    
     <dt>
<code class="parameter">offset</code></dt>

     <dd>

      <p class="para">
      通常，搜索从目标字符串的开始位置开始。可选参数 <code class="parameter">offset</code> 用于
      指定从目标字符串的某个位置开始搜索(单位是字节)。
      </p>
      <blockquote class="note"><p><strong class="note">注意</strong>: 
       <p class="para">
       使用<code class="parameter">offset</code>参数不同于向<span class="function"><strong>preg_match()</strong></span>
       传递按照位置通过<code class="literal">substr($subject, $offset)</code>截取目标字符串结果，
       因为<code class="parameter">pattern</code>可以包含断言比如<em class="emphasis">^</em>， <em class="emphasis">$</em>
       或者<em class="emphasis">(?&lt;=x)</em>。 比较：
        <div class="informalexample">
         <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$subject&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">"abcdef"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$pattern&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'/^def/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #0000BB">$pattern</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$subject</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PREG_OFFSET_CAPTURE</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">3</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
         </div>

         <p class="para">以上例程会输出：</p>
         <div class="example-contents screen">
<div class="cdata"><pre>
Array
(
)
</pre></div>
         </div>
         <p class="para">
          当这个示例使用截取后传递时
         </p>
         <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$subject&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">"abcdef"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$pattern&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'/^def/'</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #0000BB">$pattern</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">substr</span><span style="color: #007700">(</span><span style="color: #0000BB">$subject</span><span style="color: #007700">,</span><span style="color: #0000BB">3</span><span style="color: #007700">),&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">PREG_OFFSET_CAPTURE</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
         </div>

         <p class="para">
          将会产生匹配
         </p>
         <div class="example-contents screen">
<div class="cdata"><pre>
Array
(
    [0] =&gt; Array
        (
            [0] =&gt; def
            [1] =&gt; 0
        )

)
</pre></div>
         </div>
         <p class="para">
          要避免使用 <span class="function"><a href="function.substr.html" class="function">substr()</a></span>，可以用 <code class="literal">\G</code> 断言而不是 <code class="literal">^</code> 锚，或者 <code class="literal">A</code> 修改器，它们都能和 <code class="parameter">offset</code> 参数一起运行。
         </p>
        </div>
       </p>
      </p></blockquote>
     </dd>

    
   </dl>

  </p>
 </div>


 <div class="refsect1 returnvalues" id="refsect1-function.preg-match-returnvalues">
  <h3 class="title">返回值</h3>
  <p class="para">
   如果 <code class="parameter">pattern</code> 匹配到指定 <code class="parameter">subject</code>，则
   <span class="function"><strong>preg_match()</strong></span> 返回 1，如果没有匹配到则返回 0， 或者在失败时返回 <strong><code>false</code></strong>。
  </p>
  <div class="warning"><strong class="warning">警告</strong><p class="simpara">此函数可能返回布尔值
<strong><code>false</code></strong>，但也可能返回等同于 <strong><code>false</code></strong> 的非布尔值。请阅读 <a href="language.types.boolean.html" class="link">布尔类型</a>章节以获取更多信息。应使用
<a href="language.operators.comparison.html" class="link">===
运算符</a>来测试此函数的返回值。</p></div>
 </div>


 <div class="refsect1 errors" id="refsect1-function.preg-match-errors">
  <h3 class="title">错误／异常</h3>
  <p class="para">
如果传递的正则表达式无法正常解析，会发出 <strong><code>E_WARNING</code></strong>。 
</p>
 </div>


 <div class="refsect1 changelog" id="refsect1-function.preg-match-changelog">
  <h3 class="title">更新日志</h3>
  <p class="para">
   <table class="doctable informaltable">
    
     <thead>
      <tr>
       <th>版本</th>
       <th>说明</th>
      </tr>

     </thead>

     <tbody class="tbody">
      <tr>
       <td>7.2.0</td>
       <td>
        现在 <code class="parameter">$flags</code> 参数支持 <strong><code>PREG_UNMATCHED_AS_NULL</code></strong>。
       </td>
      </tr>

     </tbody>
    
   </table>

  </p>
 </div>


 <div class="refsect1 examples" id="refsect1-function.preg-match-examples">
  <h3 class="title">范例</h3>
  <p class="para">
   <div class="example" id="example-4729">
    <p><strong>示例 #1 查找文本字符串&quot;php&quot;</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">//模式分隔符后的"i"标记这是一个大小写不敏感的搜索<br /></span><span style="color: #007700">if&nbsp;(</span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">"/php/i"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"PHP&nbsp;is&nbsp;the&nbsp;web&nbsp;scripting&nbsp;language&nbsp;of&nbsp;choice."</span><span style="color: #007700">))&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"A&nbsp;match&nbsp;was&nbsp;found."</span><span style="color: #007700">;<br />}&nbsp;else&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"A&nbsp;match&nbsp;was&nbsp;not&nbsp;found."</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>
  <p class="para">
   <div class="example" id="example-4730">
    <p><strong>示例 #2 查找单词&quot;word&quot;</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">/*&nbsp;模式中的\b标记一个单词边界，所以只有独立的单词"web"会被匹配，而不会匹配<br />&nbsp;*&nbsp;单词的部分内容比如"webbing"&nbsp;或&nbsp;"cobweb"&nbsp;*/<br /></span><span style="color: #007700">if&nbsp;(</span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">"/\bweb\b/i"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"PHP&nbsp;is&nbsp;the&nbsp;web&nbsp;scripting&nbsp;language&nbsp;of&nbsp;choice."</span><span style="color: #007700">))&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"A&nbsp;match&nbsp;was&nbsp;found."</span><span style="color: #007700">;<br />}&nbsp;else&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"A&nbsp;match&nbsp;was&nbsp;not&nbsp;found."</span><span style="color: #007700">;<br />}<br /><br />if&nbsp;(</span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">"/\bweb\b/i"</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">"PHP&nbsp;is&nbsp;the&nbsp;website&nbsp;scripting&nbsp;language&nbsp;of&nbsp;choice."</span><span style="color: #007700">))&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"A&nbsp;match&nbsp;was&nbsp;found."</span><span style="color: #007700">;<br />}&nbsp;else&nbsp;{<br />&nbsp;&nbsp;&nbsp;&nbsp;echo&nbsp;</span><span style="color: #DD0000">"A&nbsp;match&nbsp;was&nbsp;not&nbsp;found."</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

   </div>
  </p>
  <p class="para">
   <div class="example" id="example-4731">
    <p><strong>示例 #3 获取URL中的域名</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">//从URL中获取主机名称<br /></span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">'@^(?:http://)?([^/]+)@i'</span><span style="color: #007700">,<br />&nbsp;&nbsp;&nbsp;&nbsp;</span><span style="color: #DD0000">"http://www.php.net/index.html"</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$host&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">];<br /><br /></span><span style="color: #FF8000">//获取主机名称的后面两部分<br /></span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">'/[^.]+\.[^.]+$/'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$host</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br />echo&nbsp;</span><span style="color: #DD0000">"domain&nbsp;name&nbsp;is:&nbsp;</span><span style="color: #007700">{</span><span style="color: #0000BB">$matches</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]}</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
domain name is: php.net
</pre></div>
    </div>
   </div>
  </p>
  <p class="para">
   <div class="example" id="example-4732">
    <p><strong>示例 #4 使用命名子组</strong></p>
    <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /><br />$str&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #DD0000">'foobar:&nbsp;2008'</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">preg_match</span><span style="color: #007700">(</span><span style="color: #DD0000">'/(?P&lt;name&gt;\w+):&nbsp;(?P&lt;digit&gt;\d+)/'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$str</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/*&nbsp;可选的方式&nbsp;*/<br />//&nbsp;preg_match('/(?&lt;name&gt;\w+):&nbsp;(?&lt;digit&gt;\d+)/',&nbsp;$str,&nbsp;$matches);<br /><br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$matches</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
    </div>

    <div class="example-contents"><p>以上例程会输出：</p></div>
    <div class="example-contents screen">
<div class="cdata"><pre>
Array
(
    [0] =&gt; foobar: 2008
    [name] =&gt; foobar
    [1] =&gt; foobar
    [digit] =&gt; 2008
    [2] =&gt; 2008
)
</pre></div>
    </div>
   </div>
  </p>
 </div>


 <div class="refsect1 notes" id="refsect1-function.preg-match-notes">
  <h3 class="title">注释</h3>
  <div class="tip"><strong class="tip">小技巧</strong>
   <p class="para">
   如果你仅仅想要检查某个字符串是否包含另外一个字符串，不要使用<span class="function"><strong>preg_match()</strong></span>。
   使用 <span class="function"><a href="function.strpos.html" class="function">strpos()</a></span> 会更快。
   </p>
  </div>
 </div>


 <div class="refsect1 seealso" id="refsect1-function.preg-match-seealso">
  <h3 class="title">参见</h3>
  <p class="para">
   <ul class="simplelist">
    <li class="member"><a href="pcre.pattern.html" class="link">PCRE 模式</a></li>
    <li class="member"><span class="function"><a href="function.preg-quote.html" class="function" rel="rdfs-seeAlso">preg_quote()</a> - 转义正则表达式字符</span></li>
    <li class="member"><span class="function"><a href="function.preg-match-all.html" class="function" rel="rdfs-seeAlso">preg_match_all()</a> - 执行一个全局正则表达式匹配</span></li>
    <li class="member"><span class="function"><a href="function.preg-replace.html" class="function" rel="rdfs-seeAlso">preg_replace()</a> - 执行一个正则表达式的搜索和替换</span></li>
    <li class="member"><span class="function"><a href="function.preg-split.html" class="function" rel="rdfs-seeAlso">preg_split()</a> - 通过一个正则表达式分隔字符串</span></li>
    <li class="member"><span class="function"><a href="function.preg-last-error.html" class="function" rel="rdfs-seeAlso">preg_last_error()</a> - 返回最后一个PCRE正则执行产生的错误代码</span></li>
    <li class="member"><span class="function"><a href="function.preg-last-error-msg.html" class="function" rel="rdfs-seeAlso">preg_last_error_msg()</a> - Returns the error message of the last PCRE regex execution</span></li>
   </ul>
  </p>
 </div>


</div></div></div></body></html>